String
This page documents the string library in Pluto, which is built on top of Lua 5.5's.
Added
string.split
Splits a string by a separator.
Parameters
- The string to split.
- The separator to split the string by.
- An optional limit for the returned table size.
Returns
A table.
Splitting a string by an empty separatorplutoprint(dumpvar("ABC":split(""))) -- { "A", "B", "C" }
Splitting a string by a single characterplutolocal s = "hello world, how is everyone doing?"print(dumpvar(s:split(" "))) -- { "hello", "world,", "how", "is", "everyone", "doing?" }
Splitting a string by a substringplutolocal s = "helloFOOworld,FOOhowFOOisFOOeveryoneFOOdoing?"print(dumpvar(s:split("FOO"))) -- { "hello", "world,", "how", "is", "everyone", "doing?" }
Splitting a string by a single character with a limitplutolocal s = "hello world, how is everyone doing?"print(dumpvar(s:split(" ", 3))) -- { "hello", "world,", "how is everyone doing?" }
string.rfind
Identical to the base Lua string.find in every way, except it searches right-to-left instead of left-to-right.
string.strip
Strips or trims characters from both ends of a string.
Parameters
- The string to strip.
- A string of characters to strip. Defaults to
\n\r\t\v\0.
Returns
The new string.
plutolocal s = "{|}hello world{|}"print(string.strip(s, "{}|")) --> hello world
string.lstrip
Strips or trims characters from the left side of a string.
Parameters
- The string to strip.
- A string of characters to strip. Defaults to
\n\r\t\v\0.
Returns
The new string.
plutolocal s = "{|}hello world{|}"print(string.lstrip(s, "{}|")) --> hello world{|}
string.rstrip
Strips or trims characters from the right side of a string.
Parameters
- The string to strip.
- A string of characters to strip. Defaults to
\n\r\t\v\0.
Returns
The new string.
plutolocal s = "{|}hello world{|}"print(string.rstrip(s, "{}|")) --> {|}hello world
string.isascii
Checks if a string is entirely composed of ASCII characters.
Parameters
- The string to check.
plutolocal s = "HELLOWORLD123"print(string.isascii(s)) --> true
This would exclude any multi-byte characters, like emojis.
string.islower
Checks if a string is entirely composed of lowercase characters.
Parameters
- The string to check.
plutolocal s = "helloworld"print(string.islower(s)) --> true
Whitespace characters are not lowercase characters.
string.isalpha
Checks if a string is entirely composed of alphabetic characters.
Parameters
- The string to check.
plutolocal s = "HELLOWORLD"print(string.isalpha(s)) --> true
Whitespace characters are not alphabetic characters.
string.isupper
Checks if a string is entirely composed of uppercase characters.
Parameters
- The string to check.
plutolocal s = "HELLOWORLD"print(string.isupper(s)) --> true
Whitespace characters are not uppercase characters.
string.isalnum
Checks if a string is entirely composed of alphanumeric characters.
Parameters
- The string to check.
plutolocal s = "HELLOWORLD123"print(string.isalnum(s)) --> true
Whitespace characters are not alphanumeric characters.
string.iswhitespace
Checks if this string is entirely composed of whitespace characters.
Paramaters
- The string to check.
plutolocal s = " \t \v \f \t\t\t\t"print(string.iswhitespace(s)) --> true
string.uformat
Same as string.format, but performs the operation under the en_US.UTF-8 locale. Ensures the same result on all systems.
string.replace
Replace substrings with another substring. Similar to string.gsub, but it operates on plain-text and is not burdened by a pattern capture limit.
Parameters
string— The string to modify.original— The substring to replace.substitute— The replacement substring.max_replace— The maximum number of replacements you wish to occur. The default value is0, which means "infinite". If you pass1, this leads to a maximum of one replacement, and so on.
Errors
An error is thrown under the following conditions:
max_replaceis less than zero.- The length of
originalis zero.
plutoprint(string.replace("Hello, world!", "!", ".")) --> Hello, world.print(string.replace("Hello, world!", "apple", "")) --> Hello, world!print(string.replace("Hello, world!", "Hello", "Apple")) --> Apple, world!print(string.replace("Hello, world!", "Hello, ", "")) --> world!
string.truncate
Truncates a given string to a specified length. If an elipsis is desired and the string was actually truncated, the last three characters of the resultant string will be replaced with an elipsis.
Parameters
- The string to truncate.
- The desired length of the truncated string.
- A boolean indicating whether or not to replace the last three character of the string with
...if it is truncated. This isfalseby default.
Returns
The truncated string.
plutoprint(string.truncate("Hello, world!", 50)) --> Hello, world!print(string.truncate("Hello, world!", 5)) --> Helloprint(string.truncate("Hello, world!", 5, true)) --> He...
string.contains
Checks if a string contains a substring.
Parameters
- The string to check.
- The substring to check for.
plutolocal s = "hello world"print(string.contains(s, "worl")) --> true
string.casefold
Compares two strings, agnostic of any capitalization.
Parameters
- The first string to compare.
- The second string to compare.
plutolocal s1 = "hello world"local s2 = "heLLo WoRlD"print(string.casefold(s1, s2)) --> true
string.formatint
This function makes an integer easier to read by inserting separator every N characters. It can handle strings representing integers, making it suitable for BigInt modules or any integer beyond Lua's representation limits. If you provide a string, it should consist solely of digits. A single unary operator is permitted at the beginning of the string to indicate whether it's a negative or positive number.
Parameters
integer— The integer or string input.sep— Theseparatorto use. This must be a single-character string.group— The grouping of each digit pair. This isN.
Errors
If the input is a string and does not meet the aforementioned criteria, an error will be thrown.
Usage Exampleplutoprint(string.formatint(500)) --> 500print(string.formatint(-5000)) --> -5,000print(string.formatint(50000)) --> 50,000print(string.formatint(-500000)) --> -500,000print(string.formatint(500, ".", 2)) --> 5.00print(string.formatint("-5000", ",", 1)) --> -5,0,0,0print(string.formatint(50000, ",", 4)) --> 5,0000
Error Exampleplutostring.formatint("-500000.4")
pluto: test.pluto:3: argument 'integer' for string.formatint was a string, but does not represent a valid integer (bad character: '.')stack traceback:[C]: in function 'string.formatint'test.pluto:3: in main chunk[C]: in ?
string.partition
Splits a string once, on the first occurance of a separator.
Parameters
- The string to partition.
- The separator to partition the string by.
- A boolean specifying whether to search from the right. By default, this is false, which starts at the left.
Returns
Two strings: A substring for all the content before the first occurance of sep, and another substring for all the content afterwards.
A Basic Partitionplutolocal s = "hello world, what's up?"local before, after = string.partition(s, " ")assert(before == "hello")assert(after == "world, what's up?")
Partioning From The Rightplutolocal s = "hello world, what's up?"local before, after = string.partition(s, " ", true)assert(before == "hello world, what's")assert(after == "up?")
string.endswith
Checks if a string ends with a suffix.
Parameters
- The string to check.
- The substring suffix to check for.
plutolocal s = "hello world"print(string.endswith(s, "world")) --> true
string.startswith
Checks if a string starts with a prefix.
Parameters
- The string to check.
- The substring prefix to check for.
plutolocal s = "hello world"print(string.startswith(s, "hello")) --> true
string.tohex
Converts a (binary) string to a hex representation.
Parameters
- The string to convert.
- An optional bool to indicate that spaces should be used.
- An optional bool to indicate that the result should be upper-cased.
Returns
A new string.
plutoprint("XYZ":tohex()) --> 58595aprint("XYZ":tohex(true)) --> 58 59 5aprint("XYZ":tohex(false, true)) --> 58595Aprint("XYZ":tohex(true, true)) --> 58 59 5A
string.fromhex
Converts a hex string to binary.
Parameters
- The string to convert.
Returns
A new string.
plutoprint("58595a":fromhex()) --> XYZprint("58 59 5A":fromhex()) --> XYZ
string.span
Returns a substring from a starting position and length. This differs from string.sub, which takes a start and end position.
Parameters
- The string.
- The starting position.
- The length.
Returns
The substring.
plutoprint("abcd":sub(2, 2)) --> bprint("abcd":span(2, 2)) --> bc
Changed
string.format
Formats a string according to a format string and a list of values, similar to C's sprintf. The format string contains conversion specifications (introduced by %) that are replaced by the corresponding values.
Supported conversions include:
%c— a character with the given numeric code%d,%i— a signed integer%o,%x,%X— an unsigned octal or hexadecimal integer%a,%A,%e,%E,%f,%g,%G— floating-point numbers%p— a pointer%q— a string or number in a form that can be read back by Lua%Q— quotes the string in a UTF-8 safe manner (Added by Pluto)%s— a string, optionally with a precision (e.g.%.3s) and width%%— a literal%
Options such as flags (-, +, space, #, 0) and width/precision may be used between % and the conversion character, as in C.
plutoprint(string.format("%d + %f = %.02f", 1, 0.2, 1.2)) --> 1 + 0.200000 = 1.20print(string.format("%q", "\xff")) --> "�"print(string.format("%Q", "\xff")) --> "\255"
string.upper
Creates an uppercased copy of a string.
Parameters
- The string to convert.
- The index of the character to capitalize. (Added by Pluto)
Returns
The new string.
plutolocal s = "hello"print(s:upper()) --> HELLOprint(s:upper(1)) --> Hello
string.lower
Creates a lowercased copy of a string.
Parameters
- The string to convert.
- The index of the character to lowercase. (Added by Pluto)
Returns
The new string.
plutolocal s = "HELLO"print(s:lower()) --> helloprint(s:lower(1)) --> hELLO
Unchanged
string.byte
Returns the internal numeric codes of the characters s[i] through s[j].
Parameters
- The string (
s). - The starting index (
i). Defaults to1. Negative indices count from the end of the string. - The ending index (
j). Defaults to the starting index.
Returns
The numeric codes of the characters in the range, as multiple values. Returns no values if the range is empty.
plutoprint(string.byte("ABC")) --> 65print(string.byte("ABC", 1, -1)) --> 65 66 67
string.char
Receives zero or more integers and returns a string whose bytes have those numeric codes.
Parameters
- The integer codes, each in the range
[0, 255].
Returns
The new string.
Errors
An error is thrown if any code is outside the range [0, 255].
plutoprint(string.char(72, 105)) --> Hi
string.dump
Returns a binary string containing a precompiled version of the function f. The string can later be passed to load to recreate the function.
Parameters
- The Lua function to dump. C functions cannot be dumped.
- An optional bool indicating if debug information should be removed from the result.
Returns
A binary string.
Errors
An error is thrown if the function cannot be dumped, such as when it is a C function.
plutolocal add = |a, b| -> a + blocal bytes = string.dump(add)local also_add = load(bytes, "=add", "b")print(also_add(2, 3)) --> 5
Be careful when referencing local values from enclosing scopes as those accesses may become invalid when loaded in a different context.
string.find
Looks for the first match of a pattern in a string.
Parameters
- The string to search.
- The pattern to search for.
- An optional starting position. Defaults to
1. Negative values count from the end of the string. - An optional bool to indicate if the pattern should be treated as plain text rather than a Lua pattern.
Returns
The start and end indices of the first match, followed by any captures from the pattern. Returns nil if there is no match.
plutoprint(string.find("hello world", "wor")) --> 7 9print(string.find("a.b.c", ".", 1, true)) --> 2 2print(string.find("key=value", "(%w+)=(%w+)")) --> 1 9 key value
string.gsub
Returns a copy of a string in which some or all occurrences of a pattern have been replaced.
Parameters
- The string to modify.
- The pattern to search for.
- The replacement. This may be a string, a table, or a function:
- If a string,
%0is replaced by the whole match and%1–%9by the corresponding captures.%%produces a single%. - If a table, the first capture (or the whole match if there are no captures) is used as the key to look up the replacement.
- If a function, it is called with the captures (or the whole match) and its return value is used as the replacement.
- If a string,
- An optional maximum number of substitutions.
Returns
The new string, and the total number of matches that were found.
plutoprint(string.gsub("hello world", "o", "0")) --> hell0 w0rld 2print(string.gsub("hello world", "(%w+)", "<%1>")) --> <hello> <world> 2print(string.gsub("$name is $age", "%$(%w+)", { name = "Ann", age = 30 })) --> Ann is 30 2print(string.gsub("abc", "%w", |c| -> string.upper(c), 2)) --> ABc 2
string.len
Returns the length of a string, in bytes. Embedded zeros are counted.
Parameters
- The string.
Returns
The length of the string.
plutoprint(string.len("abc")) --> 3print(string.len("a\0b")) --> 3
string.match
Looks for the first match of pattern in the string s.
Parameters
- The string to search.
- The pattern to search for.
- An optional starting position. Defaults to
1. Negative values count from the end of the string.
Returns
If the pattern has captures, the captured values. Otherwise, the whole match. Returns nil if there is no match.
plutoprint(string.match("hello 123", "%d+")) --> 123print(string.match("key=value", "(%w+)=(%w+)")) --> key valueprint(string.match("hello", "%d+")) --> nil
string.rep
Returns a string that is the concatenation of several copies of a given string, with an optional separator.
Parameters
- The string to repeat.
- The number of copies.
- An optional separator string placed between each copy. Defaults to the empty string.
Returns
The new string. Returns an empty string if n is less than or equal to zero.
plutoprint(string.rep("ab", 3)) --> abababprint(string.rep("ab", 3, ",")) --> ab,ab,ab
string.reverse
Returns reversed copy of a string.
Parameters
- The string to reverse.
Returns
The reversed string.
plutoprint(string.reverse("abc")) --> cba
string.sub
Returns the substring of s that starts at i and continues until j.
Parameters
- The string (
s). - The starting index (
i). Negative indices count from the end of the string. - The ending index (
j). Defaults to-1, the end of the string.
Returns
The substring.
plutoprint(string.sub("hello", 2, 4)) --> ellprint(string.sub("hello", -3)) --> llo
string.pack, string.unpack, string.packsize
These functions serialize and deserialize values to and from binary strings, according to a format string.
string.pack(fmt, ...)— Returns a binary string containing the values packed according tofmt.string.unpack(fmt, s [, pos])— Returns the values unpacked fromsstarting at positionpos(default1), followed by the next position in the string.string.packsize(fmt)— Returns the size, in bytes, of a string described byfmt. Variable-length formats (sandz) cannot be used here.
Format options:
<,>,=— Little endian, big endian, or native endianness.!n— Sets the maximum alignment tonbytes (default is native alignment).b,B— A signed or unsignedchar.h,H— A signed or unsignedshort.l,L— A signed or unsignedlong.j,J— A signed or unsignedlua_Integer.T— Asize_t.i[n],I[n]— A signed or unsignedintwithnbytes (default is the size ofint).f,d,n— Afloat,double, orlua_Number.s[n]— A string preceded by its length, stored as an unsigned integer ofnbytes (default issize_t).z— A zero-terminated string.x— One byte of padding.Xop— Aligns to the alignment of optionop, without consuming any data.
Spaces are ignored.
plutoprint(string.packsize("<i4")) --> 4local packed = string.pack("<i4s1", 1000, "hi")print(packed:tohex()) --> e8030000026869print(string.unpack("<i4s1", packed)) --> 1000 hi 8